Crate toml_edit

source ·
Expand description

toml_edit

This crate allows you to parse and modify toml documents, while preserving comments, spaces and relative order or items.

If you also need the ease of a more traditional API, see the toml crate.

Example

use toml_edit::{Document, value};

let toml = r#"
"hello" = 'toml!' # comment
['a'.b]
"#;
let mut doc = toml.parse::<Document>().expect("invalid doc");
assert_eq!(doc.to_string(), toml);
// let's add a new key/value pair inside a.b: c = {d = "hello"}
doc["a"]["b"]["c"]["d"] = value("hello");
// autoformat inline table a.b.c: { d = "hello" }
doc["a"]["b"]["c"].as_inline_table_mut().map(|t| t.fmt());
let expected = r#"
"hello" = 'toml!' # comment
['a'.b]
c = { d = "hello" }
"#;
assert_eq!(doc.to_string(), expected);

Controlling formatting

By default, values are created with default formatting

let mut doc = toml_edit::Document::new();
doc["foo"] = toml_edit::value("bar");
let expected = r#"foo = "bar"
"#;
assert_eq!(doc.to_string(), expected);

You can choose a custom TOML representation by parsing the value.

let mut doc = toml_edit::Document::new();
doc["foo"] = "'bar'".parse::<toml_edit::Item>().unwrap();
let expected = r#"foo = 'bar'
"#;
assert_eq!(doc.to_string(), expected);

Limitations

Things it does not preserve:

  • Scattered array of tables (tables are reordered by default, see test).
  • Order of dotted keys, see issue.

Modules

  • deserde
    Deserializing TOML into Rust structures.
  • serserde
    Serializing Rust structures into TOML.
  • Document tree traversal to walk a shared borrow of a document tree.
  • Document tree traversal to mutate an exclusive borrow of a document tree in place.

Structs

  • Type representing a TOML array, payload of the Value::Array variant’s value
  • Type representing a TOML array of tables
  • A parsed TOML date value
  • A parsed TOML datetime value
  • Error returned from parsing a Datetime in the FromStr implementation.
  • A prefix and suffix,
  • Type representing a TOML document
  • A value together with its to_string representation, including surrounding it whitespaces and comments.
  • A view into a single occupied location in a IndexMap.
  • Type representing a TOML inline table, payload of the Value::InlineTable variant
  • A view into a single empty location in a IndexMap.
  • Opaque string storage internal to toml_edit
  • Key as part of a Key/Value Pair or a table header.
  • A mutable reference to a Key
  • A view into a single occupied location in a IndexMap.
  • Opaque string storage for raw TOML; internal to toml_edit
  • TOML-encoded value
  • Type representing a TOML non-inline table
  • A parsed TOML time value
  • Type representing a TOML parse error
  • A view into a single empty location in a IndexMap.

Enums

  • A view into a single location in a map, which may be vacant or occupied.
  • A view into a single location in a map, which may be vacant or occupied.
  • Type representing either a value, a table, an array of tables, or none.
  • A parsed TOML time offset
  • Representation of a TOML Value (as part of a Key/Value Pair).

Traits

  • This trait represents either a Table, or an InlineTable.

Functions

  • Returns an empty array of tables.
  • Returns an empty table.
  • Returns a formatted value.

Type Aliases